Comments explain the code, not how it was found. The reap block carried the
census that motivated it, the timings that sized it, the A/B table that placed
the call site, and two quoted incidents; the test carried the same again. All of
it is in 92d2c08's message and in the PR, where it is read once rather than on
every visit to this file.

What stays is what a reader needs in order not to break it: why seven days
rather than one, why the call sits in holdPort rather than publishFingerprint,
why it is deferred, and why the prefix is one shared constant.

Production comment lines 36 -> 25; no behaviour change, tests unchanged and green.

Co-Authored-By: Claude <noreply@anthropic.com>

Age alone made the seven-day gate a deadline rather than a margin. Nothing
republishes a record — publishFingerprint has one call site, the spawn path — so
a holder that neither respawns nor is redeployed for a week is fully live with an
over-age record, and the next launcher to start deleted it. runningOurCode() then
answers null, holderVerdict returns "holder", and takeOver() exits 0 announcing a
deploy that has not taken effect: the incident the launcher already documents,
made reachable by the fix meant to prevent litter.

Measured end to end before this commit: a scratch TMPDIR holding an 8-day-old
record for a live holder's port, one unrelated run-service start, record gone.

So ask lsof, which the launcher already relies on for holderPidOn and
otherHolderOn and which works on macOS. One call, made only once a record is
actually eligible, so a swept host still pays nothing but a readdir. A probe that
cannot answer keeps everything rather than reading "could not ask" as "nothing is
listening" — that reading would hand the reaper every record on the box.

The age gate stays, now bounding what a crashed holder leaves on a port nobody
rebinds rather than standing alone.

Two comment claims corrected. The scratch-CA reaper does not share a walk with
this one: it sits after `await dispatch()` and runs in wrapper mode only, never
in a run-service holder. And "age is the only discriminator available" was false
— a listening-port set was one lsof away, which is what this commit uses.

Tests: a live-listener case, a probe-cannot-answer case, and a case that spawns a
real run-service and waits for a planted stale record to vanish. That last one
exists because every other case runs lifted source and none of them can see
whether the launcher ever calls the reaper — commenting the call out left them
all green.

Co-Authored-By: Claude <noreply@anthropic.com>

The case added to prove the reaper is reachable spawns a run-service and
SIGKILLs it. run-service leaves a DETACHED standby gap-relay that stands down
only for a claimant's SIGHUP, so killing the launcher reparented it to init
still holding an ephemeral port. Measured: one per run, eight alive at once
here, the oldest over three hours, each one a listener in the range the
suite's own fixtures bind.

proc-helpers exports onPort for exactly this and its comment already records the
same incident from proxy-held-port. Not importing it was the whole defect.
Holder first, then whatever is left on the port, which is the order that file's
sweep documents. Measured after: orphan delta 0 across three consecutive runs,
and no ccf-fpreap-* scratch left behind.

suite-collection gains a guard for it, named rather than swept. A form-based
sweep — every .test.mjs carrying both "run-service" and SIGKILL — was tried and
measured: it also flags proxy-probe-bounded and stdio-epipe-survival, whose
orphan delta over a full run is 0, because they spawn a holder that never
reaches the standby. The predicate describes the shape of the code rather than
the debt it incurs, and a guard that reds two innocent files is one someone
deletes.

Co-Authored-By: Claude <noreply@anthropic.com>

CI went red on Node 18 and the cause was not the Node version — it was lsof.
Reproduced locally by running the file with lsof off PATH: 3 of 6 cases fail,
the same failure CI reported. listeningPorts() shelled out, a missing lsof threw,
and the fail-closed branch then kept every record, so the reaper became a silent
no-op. The leak fix would have done nothing on any host without lsof, which is
exactly where nobody would look for it.

A bind answers the same question with no external tool. holderPidOn needs a PID
and has to shell out; this needs one bit, and the kernel gives it directly. It is
also exact where lsof was not: lsof sees only this uid, so a holder under another
account read as "nothing is listening".

The reap was already deferred with setTimeout and nothing awaits it, so making it
async costs nothing. Every path still catches, so there is no unhandled rejection
to leak out of the timer.

A name whose port is not a number is kept rather than judged — listen(NaN) throws
ERR_SOCKET_BAD_PORT rather than answering, and cache-fix-proxy-healthcheck.* is a
name this reaper has no business deciding about.

Measured: 6/6 with lsof present, 6/6 with lsof off PATH. Mutations killed —
removing the port guard, and inverting the non-numeric case to reap.

Co-Authored-By: Claude <noreply@anthropic.com>

The guard added alongside the orphan fix named proxy-fingerprint-reap directly,
which is the same blindness the guard above it already had: it goes stale the
moment a third file learns the debt. It now scans every .test.mjs that spawns a
launcher and SIGKILLs it, and accepts any spelling of the sweep — onPort(),
listeners(), or a raw lsof -iTCP. stdio-epipe-survival sweeps with the last of
those, and a predicate that only knew the first would have called it an offender.

A file that kills a launcher and genuinely owes no sweep says so with NO-STANDBY:
and why. proxy-probe-bounded is the one: the hang under test is a probe, so the
launcher blocks before it ever binds and there is no detached standby to
reparent. Measured with its deadline forced to 200 ms, 3 s and 6 s — orphan delta
0 at all three.

Measured over all 24 test files: 5 sweep, 1 exempt, 0 offenders. Mutations killed
— removing the onPort sweep reds it, and removing the marker reds it naming
proxy-probe-bounded.

Co-Authored-By: Claude <noreply@anthropic.com>

Three claims were stronger than what had been measured, all in permanent records.

4411af4's message said "measured over all 24 test files: 5 sweep, 1 exempt, 0
offenders". That number came from a review summary rather than from running the
predicate. Run here over the guard's own testDir: 114 .test.mjs, 7 candidates,
6 sweep, 1 exempt, 0 offenders. The guard was right; the census reporting it was
not, and it omitted proxy-fingerprint-reap itself.

The "~80 ms before the gap relay boots" was borrowed from a nearby comment that
measured the proxy CHILD's boot, a much larger spawn. Nothing measured the relay,
so the comment now says the window is unmeasured rather than naming a number.

And portFree is itself a listener while it asks. A launcher starting concurrently
runs otherHolderOn(), which selects on a LISTEN socket plus a run-service command
line plus greater uptime; a peer mid-probe can satisfy all three and be read as an
incumbent. Bounded by the bind lifetime, under 59 µs per record, and now stated.

Co-Authored-By: Claude <noreply@anthropic.com>

The predicate accepted `-iTCP` as a spelling of "sweeps the port", and
stdio-epipe-survival passed on it. That file's `lsof -iTCP` is its STIMULUS —
it kills the proxy child mid-body to provoke a restart log, three lines above
the assertion — while its actual cleanup is `t.after(() => reap(holder))`, a
process-GROUP kill. The file was protected the whole time, by a mechanism the
guard could not see, and passed on a coincidental substring.

A group kill reaps the standby as a child of the group without ever naming a
port, so it discharges the same debt. The predicate now names that instead of a
third spelling of lsof, and the comment says which three mechanisms count and
why they look nothing alike.

Measured: all 24 candidates reclassify identically (6 sweep, 1 exempt, 0
offenders), and removing the group kill from stdio-epipe-survival now reds the
guard naming that file.

Co-Authored-By: Claude <noreply@anthropic.com>

… code

CI went red on Node 22 with `body.startsWith is not a function`, inside "refuses
nothing when the proxy under it dies". Six of this file's seven probes resolve
`ERR:${e.code}` — a string with the prefix classify() tests for. The seventh, at
the forced-kill case, resolves a bare `r.statusCode` on success and a bare
`e.code` on error. Its caller filters out 200 and hands everything else to
classify(), so a 502 arrives as a Number and the case dies where the answer is
simply "that was a reply, not an outage".

The path only opens when a non-200 is actually observed, which is why it survived
every local run and three CI matrices before this one. A unit case pins it now:
a status code classifies as null, an ERR: string still classifies, and a bare
ECONNRESET with no prefix stays null.

Measured: removing the type guard reds that case with the exact CI message.

Nothing else on this branch touches this file — the crash predates it and was
merely surfaced here. It rides along rather than waiting behind its own PR
because leaving this branch red would mean explaining the red in a comment and
making the two land in a fixed order, for a five-line guard.

Co-Authored-By: Claude <noreply@anthropic.com>

…shared hop

The spawn case set CACHE_FIX_FORWARD_PROXY=on and pinned TMPDIR but not
CLAUDE_CONFIG_DIR, so the launcher minted a CA in the operator's real config
dir and republished ca-trust.d/ccf.pem, the rendezvous file every sibling
component reads, from under whatever proxy was serving. Measured with the
config dir redirected to a probe: it holds ca-trust.d and cache-fix-ca after
the case, and stays empty without the variable. The reap needs no CA, so the
variable goes and the config dir joins TMPDIR in the scratch dir the case
already removes.

The hop scrub was a hand-written four-name list standing beside the shared
nine-name one this file already imports from. It left CACHE_FIX_UPSTREAM_PROXY
and CACHE_FIX_FALLBACK_PROXIES, the two the relay reads first, in the child.

releasedPort() re-implemented the shared freePort() byte for byte, and the
presence assertion on recordAgeMs guarded nothing the age cases do not already
cover: with the gate disabled the stale-record case fails on its own.

Co-Authored-By: Claude <noreply@anthropic.com>

54 of the 83 lines this change added to the launcher were comment, and most of
the surplus was one run's numbers: microseconds per bind, milliseconds held
per thousand records, a sizing budget for a scan nothing waits on. They date
the file without telling a reader anything the code does not.

Kept: why a listening port outranks the clock, what losing a live holder's
record costs, and both directions of the gap between "is anything listening"
and "is anyone using this port".

Co-Authored-By: Claude <noreply@anthropic.com>

The classify() guard and the unit case below it carried the same six-line
account of the seventh probe; one copy is the record, two is drift waiting
to happen. portFree's third paragraph restated the deferral its call site
already states, and the yield invariant it also carried is kept.

The non-numeric-port case built a whole scratch dir to assert one filename
survives. The multi-name case already builds one and runs the same reaper,
so the name joins it there, over-age so it still reaches portFree.

net: -18 lines. No behaviour change; 22/22 pass on the two files that hold
the reaper's tests and the suite-wide guards.

Co-Authored-By: Claude <noreply@anthropic.com>

Three full-suite runs went red in this file at three different cases, about
two seconds in, two of them on JSON.parse at position 3. Nobody had named
what answers 200 with such a body. It is us.

takePort() binds 0, reads the port and RELEASES it before the launcher binds
it, and every worker draws from one ephemeral pool: measured, 1317 of 4000
ports drawn by that allocator were handed to a concurrently running process
in the same window. Two files stand up a stand-in release channel on
127.0.0.1:0 that answers ANY path with 200 and a bare version string, and
`JSON.parse("2.1.222")` dies at exactly position 3 — a three-character JSON
number followed by a dot. A census of every literal HTTP body in test/,
proxy/ and bin/ finds no other responder in the tree that lands there.

So the readiness rule was the defect, not the launcher: four loops here broke
out on the first 200 and handed it to a bare JSON.parse, which reds the
holder's case for a neighbour's fixture. readyBody() is the one test for "the
holder is up", the loops poll until it or the deadline, and the last body
still rides along on a real timeout.

Also: the stand-in readiness budget in the forced-kill case was 10s, the
outlier in a file where every other launcher-spawned child gets 15s or 20s.
It expired under load on a case that costs 3.3s quiet.

37/37 pass in this file. Mutation-checked: with the predicate back to
!startsWith("ERR:"), the new case reds as "a release channel's 200 read as
readiness", actual true, expected false.

Co-Authored-By: Claude <noreply@anthropic.com>

Review findings, each mutation-checked against the final code.

RECORD_PREFIX existed so the writer and the reaper could not drift apart.
The suffix could still drift: fingerprintPath built ".sha256" in a template
while the reaper matched and sliced three separate literals. Nothing caught
it either, because the fixtures hardcoded the suffix on both sides, so a
change at the writer left the reaper matching nothing, collecting nothing,
and every case green. RECORD_SUFFIX now, derived by the test from the
launcher's own source. Mutation: ".sha256" to ".fp" reds 3 of 5 cases.

The scan was deferred so it would not delay the bind, and then held the
event loop anyway: nothing it awaits reaches the poll phase, so an
uninterrupted pass blocks between the bind and the first accept. One
periodic setImmediate. Measured at 300 records: a setImmediate queued first
fires 13 ms into a 28 ms scan with the yield and not at all without it, and
the total is unchanged.

The seven-day gate was two independent literals a thousand lines apart, one
of them justified by a comment saying it matches the other. One REAP_AGE_MS,
read by both reapers.

Two gaps the probe has and did not name: a record is keyed by port alone
while portFree asks about bindAddr(), so a holder on another address reads
as free; and the probe is itself a listener, so a launcher in otherHolderOn()
can call it an incumbent and settle(0) on an empty port. Both now stand
beside the LISTEN-vs-ownership gap, with the shared consequence stated once.
Not closed here: the wildcard probe that would fix the first opens an
externally reachable socket per over-age record, and carrying the address
would change the record format.

The port floor is load-bearing and now has a case: listen(0) takes a random
free port and always succeeds, so without it every port-0 record reads as
collectable, and port 0 is a name older versions demonstrably wrote. The
CEILING is invisible from the directory — listen() throws, the inner catch
keeps the record, and a fixture asserting the record survived passes with
the guard deleted. Measured, then replaced with a direct question to the
predicate, where answering false and rejecting differ.

5/5 in the reap file, 37/37 in held-port, 22/22 across the guards.

Co-Authored-By: Claude <noreply@anthropic.com>

rec() was added with the constant-derivation change and never wired to a
call site. A one-use local alias for REAP_AGE_MS stood in front of the
constant it aliases. And a comment above the deferral assertion restated
the assertion's own message, which is the half that reaches a failing run.

net: -4 lines. 23/23 across the reap file and the suite-wide guards.

Co-Authored-By: Claude <noreply@anthropic.com>

…l it

The reaper e2e case initialises `port = 0` and assigns it from freePort()
seven lines later; its finally sweeps onPort(port) unconditionally. Anything
that throws in between aims that sweep at port 0.

ours() reads CACHE_FIX_PROXY_PORT, and a proxy child legitimately carries 0
there when it inherits the holder's listening fd. So onPort(0) is not the
empty set it looks like. Measured read-only on a dev host: 7 processes, one
of them the deployed proxy every session on the box routes through.

Guarded at onPort() rather than the call site -- three other files sweep
through it and none of them state the invariant either. listeners(0) is
already empty (nothing listens on port 0), so the whole hole is ours().

The new case carries its own control: it asserts the helper DOES find a stub
on a real port before asserting it does not find one on 0. Without that, a
host with no proxy running passes it vacuously.

RED: onPort(0) selected a process carrying CACHE_FIX_PROXY_PORT=0
GREEN: 6/6 in the file, 104/104 across every file that calls onPort

Co-Authored-By: Claude <noreply@anthropic.com>

publishFingerprint writes `<record>.<pid>` and renames. The suffix test skips
that name, so a publish that died between the write and the rename leaves a
file no reaper anywhere ever collects -- and the case in this file pinned that,
asserting an EIGHT-DAY-OLD temp must survive as "a concurrent launcher's
pending write".

A rename pends for microseconds. Past the same seven-day gate the only thing
that leaves one behind is a crash, and the scratch-CA reaper twenty lines below
already answers this exact question for its own artifacts rather than sparing
them forever.

The protection is kept and split from the leak: a FRESH temp still survives
untouched, an over-age one is collected. A temp answers to no port, so it skips
portFree -- nothing reads it.

RED: an eight-day-old <record>.<pid> survived: no reaper anywhere collects it
GREEN: 6/6 in the file

Co-Authored-By: Claude <noreply@anthropic.com>